Version: 1.3.4

LOR API Documentation

Directory APIs

Root Directory Retrieval Endpoint

Method: GET
Path: https://api.kadal.ai/cl/api/v1/directory/root
Summary: Gets the root directory for the current tenant.

Description

Returns the root directory information for a tenant if it exists.

Request

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	string	UUIDs	optional

Response

{
  "status_code": "200",
  "message": "Root directory found",
  "data": [{
    "name": "root_ABC12",
    "folder_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "type": "Folder",
    "is_private": false,
    "custom_metadata": {}
  }]
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v1/directory/root"
token = "YOUR_TOKEN"

headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(url, headers=headers)
print(response.json())

Root Directory Creation Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v1/directory/root
Summary: Creates a root directory for a tenant.

Description

Creates a root directory for a tenant. The root directory will be named as root_{tenant_code}.

Request

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	string	UUIDs	optional

Payload

Field	Type	Description	Validation
tenant_code	string	Tenant identifier	5 character alphanumeric code

Response

{
  "status_code": "201",
  "message": "Successfully created root directory"
}

Other Responses
- 409 Conflict: Can't create duplicate root directory

Usage

import requests

url = "https://api.kadal.ai/cl/api/v1/directory/root"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "tenant_code": "ABC12"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Directory Retrieval Endpoint

Method: GET
Path: https://api.kadal.ai/cl/api/v1/directory/{folder_id}
Summary: Gets information about a specific directory.

Description

Gets folder information for a specific directory and shows information for all children present inside the requested directory.

Request

Query Parameters
- folder_id (path): UUID of the directory to retrieve
- sorting_by (query, optional): Sort result by title or modified_date (default: updated_at)
- order (query, optional): Sort order (asc/desc, default: asc)
- ext_user_id_ref (query, optional): External user ID reference

Response

{
  "status_code": "200",
  "message": "Child directory found.",
  "data": [{
    "name": "Directory Name",
    "folder_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "type": "Folder",
    "is_private": false,
    "custom_metadata": {},
    "children": []
  }]
}

Directory Metadata Update Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v1/directory/{folder_id}
Summary: Updates metadata of a directory.

Description

Updates metadata of a directory (non-root directories only). Usage rules:

This API updates only the metadata of an existing directory — it does not add or remove child directories.
To replace a directory structure, use the DELETE /{folder_id} API first, then POST /{parent_id} to recreate it.
All fields are optional, but at least one must be provided.
To clear all custom metadata, pass custom_metadata as an empty object {}.
To clear individual fields: pass tags as [], kvp as [], taxonomy as [].

Request

Content-Type: application/json
Path Parameters

Parameter	Description	Data Type	Required
folder_id	UUID of the directory to update	String (UUID)	Yes

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	String	UUID	No

Payload

Parameter	Description	Data Type	Allowed Values	Required
name	Directory display name	String		No
is_private	Privacy flag	Boolean	`true`, `false`	No
type	Directory type	String	Folder, Module, etc.	No
description	Directory description	String		No
custom_metadata	Custom metadata object	Object	`{ tags: [], kvp: [], taxonomy: [] }`	No

{
  "name": "Folder 1",
  "is_private": false,
  "type": "Folder",
  "description": "Updated description",
  "custom_metadata": {
    "tags": [],
    "kvp": [],
    "taxonomy": []
  }
}

Response

{
  "status_code": "200",
  "message": "Sucessfully updated child directory"
}

Other Responses
- 400 Connection error
- 403 Forbidden
- 404 Not found
- 409 Conflict
- 422 Validation Error
- 500 Internal server error

Usage

import requests

folder_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/directory/{folder_id}"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

payload = {
    "name": "Updated Folder",
    "is_private": False,
    "type": "Folder",
    "description": "Updated description",
    "custom_metadata": {
        "tags": [],
        "kvp": [],
        "taxonomy": []
    }
}

response = requests.put(url, headers=headers, json=payload)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Child Directories Addition Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v1/directory/{folder_id}
Summary: Add one or more directories to an existing directory.

Description

Adds one or more directories to a parent directory. The parent directory can be a root directory or any other existing directory. A complete nested directory structure can be created in a single request using the children array. custom_metadata is optional; if not provided, it defaults to an empty object.

Request

Content-Type: application/json
Path Parameters

Parameter	Description	Data Type	Required
folder_id	UUID of the parent directory	String (UUID)	Yes

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	String	UUID	No

Payload

Parameter	Description	Data Type	Allowed Values	Required
directory_structure	Array of directory objects to create	Array of Objects		Yes
directory_structure[].name	Directory display name	String		Yes
directory_structure[].is_private	Privacy flag	Boolean	`true`, `false`	No
directory_structure[].type	Directory type	String	Folder, Module, etc.	No
directory_structure[].project_id	Associated project ID	String	UUID	No
directory_structure[].description	Directory description	String		No
directory_structure[].children	Nested child directories	Array		No
directory_structure[].custom_metadata	Custom metadata	Object		No
directory_structure[].custom_metadata.tags	Tag list	Array of Objects	`[{ name: string, is_system: bool }]`	No
directory_structure[].custom_metadata.kvp	Key-value pairs	Array of Objects	`[{ metadata_id, key, value, type, is_system }]`	No
directory_structure[].custom_metadata.taxonomy	Taxonomy entries	Array of Objects	`[{ metadata_id, version_id, title, code }]`	No

{
  "directory_structure": [
    {
      "name": "Folder 1",
      "is_private": false,
      "type": "Folder",
      "project_id": "string",
      "description": "string",
      "children": [],
      "custom_metadata": {
        "tags": [
          { "name": "string", "is_system": false }
        ],
        "kvp": [
          {
            "metadata_id": "string",
            "key": "string",
            "value": "string",
            "type": "string",
            "is_system": false
          }
        ],
        "taxonomy": [
          {
            "metadata_id": "string",
            "version_id": "string",
            "title": "string",
            "code": "string"
          }
        ]
      }
    }
  ]
}

Response

{
  "status_code": "201",
  "message": "Sucessfully added children to parent directory"
}

Other Responses
- 206 Partially added — some directories were added successfully
- 400 Connection error
- 404 Not found
- 409 Conflict
- 422 Validation Error
- 500 Internal server error

Usage

import requests

folder_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/directory/{folder_id}"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

payload = {
    "directory_structure": [
        {
            "name": "Folder 1",
            "is_private": False,
            "type": "Folder",
            "description": "A new folder",
            "children": [],
            "custom_metadata": {
                "tags": [{"name": "tag1", "is_system": False}],
                "kvp": [
                    {
                        "metadata_id": "meta-uuid",
                        "key": "key1",
                        "value": "value1",
                        "type": "string",
                        "is_system": False
                    }
                ],
                "taxonomy": [
                    {
                        "metadata_id": "tax-uuid",
                        "version_id": "v1-uuid",
                        "title": "Taxonomy Title",
                        "code": "TAX001"
                    }
                ]
            }
        }
    ]
}

response = requests.post(url, headers=headers, json=payload)

if response.status_code in (200, 201):
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Directory Deletion Endpoint

Method: DELETE
Path: https://api.kadal.ai/cl/api/v1/directory/{folder_id}
Summary: Deletes a directory and its contents.

Description

Deletes a directory that is other than a root directory and all its underlying directories.

Request

Query Parameters
- folder_id (path): UUID of the directory to delete
- ext_user_id_ref (query, optional): External user ID reference

Response

{
  "status_code": "200",
  "message": "Successfully deleted directory"
}

Usage

import requests

token = "YOUR_TOKEN"
folder_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/directory/root/children/{folder_id}"
headers = {
    "Authorization": f"Bearer <token>"
}

response = requests.delete(url, headers=headers)
print(response.json())

Bulk Directory Retrieval Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v1/directory/details/bulk
Summary: Gets information about multiple directories.

Description

Gets folder information for multiple folders and shows information for all children present inside each requested directory.

Request

Query Parameters
- ext_user_id_ref (optional): External user ID reference
Payload

{
  "folder_ids": [
    "1ea3d628-f555-41c7-8101-c56a65087bab",
    "2fb4d839-g666-52d8-9212-d67b76198bac"
  ]
}

Response

{
  "status_code": "200",
  "message": "Directories found",
  "data": [{
    "name": "Directory Name",
    "folder_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "type": "Folder",
    "is_private": false,
    "custom_metadata": {},
    "children": []
  }]
}

Directory Search Endpoint

Method: POST
Path: https://api.kadal.ai//cl/api/v1/directory/aggregate/details
Summary: Searches for directories based on a query string.

Description

Gets all folder information for a tenant matching the search criteria.

Request

Query Parameters
- query_string (optional): Query string to search for folders
- sort_by (optional): Sorting field (default: updated_at)
- order (optional): Sort order (default: asc)
- page_no (optional): Page number (default: 1)
- page_size (optional): Page size (default: 20)
- ext_user_id_ref (optional): External user ID reference

Response

{
  "status_code": "200",
  "message": "Directories found",
  "data": {
    "total": 50,
    "page": 1,
    "size": 20,
    "results": [{
      "name": "Directory Name",
      "folder_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
      "type": "Folder",
      "is_private": false,
      "custom_metadata": {}
    }]
  }
}

My Folder APIs

My Folder Upsert Endpoint

Method: GET
Path: https://api.kadal.ai/cl/api/v1/my_folder
Summary: Gets a user's private folder or creates it if it doesn't exist.

Description

Gets the private folder of a user. If the private folder does not exist, it will be created.

Response

{
  "status_code": "200",
  "message": "Successfully retrieved my_folder",
  "my_folder_directory_id": "0ad38b25-f71a-48e5-b649-c912a5350f40"
}

Other Responses
- 404 Not Found: Root directory not found (required to create my_folder)

Notes

The my_folder directory is created as a private folder under the tenant's root directory
The folder has chat_interface_only: true set in its custom metadata
Only the owner can access their my_folder directory

Usage

import requests

url = "https://api.kadal.ai/cl/api/v1/my_folder"
headers = {
    "Authorization": "Bearer <your_token>"
}

response = requests.get(url, headers=headers)
print(response.json())

Get Objects Content API

Method: GET
Path: https://api.kadal.ai/cl/api/v1/objects/{object_id}/content
Summary: Get object content by ID and type.

Description

Get object content by ID and type (e.g. toc, extracted_text, summary, etc.)

Request

Path Parameters

Parameter	Description	Data Type	Allowed Values	Required
object_id	Object ID	string	UUID	required

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
type	Content type to retrieve	string	extracted_text, summary_text, content_text, toc	optional (default: toc)
ext_user_id_ref	External user ID reference	string	UUID	optional

Response

{
  "status_code": 200,
  "message": "Object content retrieved successfully",
  "data": [
    "This document outlines the professional profile and projects of a data scientist with over three years of experience. The individual possesses expertise in advanced data analysis"
  ],
  "breadcrumb": []
}

Other Responses
- 404 Not Found: Object not found
- 400 Bad Request: Invalid parameters

Usage

Python Example:

import requests

object_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/objects/{object_id}/content"
headers = {
    "Authorization": "Bearer <your_token>"
}
params = {
    "type": "summary_text"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

cURL Example:

curl -X 'GET' \
  'https://api.kadal.ai/cl/api/v1/objects/00680ef7-9e14-4e21-b68b-b74e5b0ab613/content?type=summary_text' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_token>'

Objects V2 APIs

Object Creation Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v2/objects
Summary: Creates a new object in the repository.

Description

Creates a new object in the object repository. The source_category under system_metadata can be KnowledgeBase/Guideline/OutputTemplate.

Request

Payload

Field	Type	Description	Validation
object_id	string	Optional UUID for the object	UUID format
title	string	Object title	Required
description	string	Object description	Optional
system_metadata	object	System metadata	Required
system_metadata.source	string	Source of the object	Required
system_metadata.source_category	string	Category (KnowledgeBase/Guideline/OutputTemplate)	Required
system_metadata.is_private	boolean	Privacy flag	Required
system_metadata.mime_type	string	MIME type of object	Required for files
system_metadata.file_extension	string	File extension	Required for files
system_metadata.file_size	number	Size in bytes	Required for files
system_metadata.is_latest_version	boolean	Latest version flag	Required
custom_metadata	object	Custom metadata	Optional
custom_metadata.kvp	object	Key-value pairs	Optional
custom_metadata.tags	array	Tags list	Optional
custom_metadata.taxonomy	array	Taxonomy information	Optional

{
  "object_id": "optional-uuid-if-client-wants-to-specify",
  "title": "Object Title",
  "description": "Object Description", 
  "system_metadata": {
    "source": "KnowledgeBase",
    "source_category": "Guideline",
    "is_private": false,
    "mime_type": "application/pdf",
    "file_extension": "pdf",
    "file_size": 1024,
    "is_latest_version": true
  },
  "custom_metadata": {
    "kvp": {
      "key1": "value1"
    },
    "tags": [
      "tag1"
    ],
    "taxonomy": [
      {
        "uuid": "taxonomy-id",
        "title": "Taxonomy Title"
      }
    ]
  }
}

Response

{
  "status": "200",
  "message": "Object created successfully",
  "data": {
    "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "version_id": "v1"
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/objects"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "title": "Object Title",
    "description": "Object Description",
    "system_metadata": {
        "source": "KnowledgeBase",
        "source_category": "Guideline",
        "is_private": False,
        "mime_type": "application/pdf",
        "file_extension": "pdf",
        "file_size": 1024,
        "is_latest_version": True
    },
    "custom_metadata": {
        "kvp": {"key1": "value1"},
        "tags": ["tag1"],
        "taxonomy": [{"uuid": "taxonomy-id", "title": "Taxonomy Title"}]
    }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Object Update Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v2/objects/{object_id}
Summary: Updates an existing object's latest version.

Description

Updates an object in the repository. Can update metadata and content.

Request

Query Parameters
- object_id (path): UUID of the object to update
Payload

Field	Type	Description	Validation
title	string	Updated title	Optional
description	string	Updated description	Optional
system_metadata	object	Updated system metadata	Optional
system_metadata.is_private	boolean	Updated privacy flag	Optional
system_metadata.mime_type	string	Updated MIME type	Optional
system_metadata.file_extension	string	Updated file extension	Optional
system_metadata.file_size	number	Updated size in bytes	Optional
custom_metadata	object	Updated custom metadata	Optional
custom_metadata.kvp	object	Updated key-value pairs	Optional
custom_metadata.tags	array	Updated tags list	Optional
custom_metadata.taxonomy	array	Updated taxonomy info	Optional

{
  "title": "Updated Title",
  "description": "Updated Description",
  "system_metadata": {
    "is_private": true,
    "mime_type": "application/pdf",
    "file_extension": "pdf",
    "file_size": 2048
  },
  "custom_metadata": {
    "kvp": {
      "key1": "updated_value"
    },
    "tags": [
      "new_tag"
    ],
    "taxonomy": [
      {
        "uuid": "new-taxonomy-id",
        "title": "New Taxonomy"
      }
    ]
  }
}

Response

{
  "status": "200",
  "message": "Object updated successfully",
  "data": {
    "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "version_id": "v2"
  }
}

Usage

import requests

object_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v2/objects/{object_id}"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "title": "Updated Title",
    "description": "Updated Description",
    "system_metadata": {
        "is_private": True,
        "mime_type": "application/pdf",
        "file_extension": "pdf",
        "file_size": 2048
    },
    "custom_metadata": {
        "kvp": {"key1": "updated_value"},
        "tags": ["new_tag"],
        "taxonomy": [{"uuid": "new-taxonomy-id", "title": "New Taxonomy"}]
    }
}

response = requests.put(url, headers=headers, json=payload)
print(response.json())

Object Retrieval Endpoint

Method: GET
Path: https://api.kadal.ai/cl/api/v2/objects/{object_id}
Summary: Retrieves an object by ID.

Description

Gets object details including all metadata and versions.

Request

Query Parameters
- object_id (path): UUID of the object to retrieve

Response

{
  "status": "200",
  "message": "Object found",
  "data": {
    "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "title": "Object Title",
    "description": "Object Description",
    "system_metadata": {
      "source": "KnowledgeBase",
      "source_category": "Guideline",
      "is_private": false,
      "mime_type": "application/pdf",
      "file_extension": "pdf",
      "file_size": 1024,
      "is_latest_version": true,
      "created_by": "user-id",
      "created_by_name": "User Name",
      "created_at": "2024-08-05T12:31:23.939Z",
      "updated_by": "user-id",
      "updated_by_name": "User Name",
      "updated_at": "2024-08-05T18:36:02.772Z"
    },
    "custom_metadata": {
      "kvp": {
        "key1": "value1"
      },
      "tags": [
        "tag1"
      ],
      "taxonomy": [
        {
          "uuid": "taxonomy-id",
          "title": "Taxonomy Title"
        }
      ]
    },
    "versions": [
      {
        "version_id": "v1",
        "created_at": "2024-08-05T12:31:23.939Z",
        "created_by": "user-id",
        "created_by_name": "User Name"
      }
    ]
  }
}

Usaage

import requests

object_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/objects/{object_id}"
headers = {
    "Authorization": "Bearer <your_token>"
}

response = requests.get(url, headers=headers)
print(response.json())

Object Deletion Endpoint

Method: DELETE
Path: https://api.kadal.ai/cl/api/v2/objects/{object_id}
Summary: Deletes an object from the repository.

Description

Deletes the specified object and all its versions.

Request

Query Parameters
- object_id (path): UUID of the object to delete

Response

{
  "status": "200",
  "message": "Object deleted successfully"
}

Usage

import requests

object_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v2/objects/{object_id}"
headers = {
    "Authorization": "Bearer <your_token>"
}

response = requests.delete(url, headers=headers)
print(response.json())

Objects Listing Endpoint

Method: GET
Path: https://api.kadal.ai/cl/api/v2/objects
Summary: Lists all objects in the repository.

Description

Gets a paginated list of all objects.

Request

Query Parameters
- page (optional): Page number (default: 1)
- size (optional): Items per page (default: 20)
- sort_by (optional): Field to sort by (title/updated_at)
- order (optional): Sort order (asc/desc)

Response

{
  "status": "200", 
  "message": "Objects found",
  "data": {
    "total": 50,
    "page": 1,
    "size": 20,
    "results": [
      {
        "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
        "title": "Object Title",
        "description": "Object Description",
        "system_metadata": {
          "source": "KnowledgeBase",
          "source_category": "Guideline",
          "is_private": false,
          "mime_type": "application/pdf",
          "file_extension": "pdf",
          "file_size": 1024,
          "is_latest_version": true,
          "created_at": "2024-08-05T12:31:23.939Z",
          "updated_at": "2024-08-05T18:36:02.772Z"
        },
        "custom_metadata": {
          "kvp": {
            "key1": "value1"
          },
          "tags": ["tag1"],
          "taxonomy": [{
            "uuid": "taxonomy-id",
            "title": "Taxonomy Title"
          }]
        }
      }
    ]
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/objects"
headers = {
    "Authorization": "Bearer <your_token>"
}
params = {
    "page": 1,
    "size": 20,
    "sort_by": "title",
    "order": "asc"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

Move bulk folders and objects Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v2/objects/move/bulk
Summary: Move bulk folders and objects to a folder

Description

Move bulk folders and objects to a folder

Request

Payload

Field	Type	Description	Validation
object_ids	array	List of object UUIDs	Each item UUID
folder_ids	array	List of folder UUIDs	Each item UUID
update_fields	object	Fields to update	Required
update_fields.parent_id	string	Parent folder/object ID	UUID format
update_fields.is_private	boolean	Privacy flag for the object/folder	Required (true/false)

{
"object_ids": [
  "string"
],
"folder_ids": [
  "string"
],
"update_fields": {
  "parent_id": "string",
  "is_private": true
}
}

Response

{
  "status": "string",
  "message": "string",
  "data": {
    "status": "string",
    "object_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "version_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "version_no": 1,
    "version_label": "string",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "object_type": "string",
    "title": "string",
    "description": "string",
    "file_name": "string",
    "file_extension": "string",
    "size": 0,
    "mimetype": "string",
    "uri": "string",
    "asset_location": "string",
    "default_asset_thumbnail": "string",
    "created_at": "2025-12-22T06:57:55.139Z",
    "updated_at": "2025-12-22T06:57:55.139Z",
    "deleted_at": "2025-12-22T06:57:55.139Z",
    "created_by_name": "string",
    "created_by_user_id": "string",
    "created_by_user_type": "string",
    "updated_by_name": "string",
    "deleted_by_name": "string",
    "is_latest_version": false,
    "is_deleted": false,
    "is_private": false,
    "is_lga": "string",
    "source": "string",
    "tags": [
      "string"
    ],
    "kvp": {},
    "taxonomy": [
      {
        "uuid": "string",
        "title": "string"
      }
    ],
    "folders": [
      "string"
    ],
    "repos": [
      "string"
    ],
    "metadata": {},
    "media": {},
    "usage_count": 0,
    "license_expiration_date": "2025-12-22T06:57:55.139Z",
    "license_validity": true
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/objects/move/bulk"
headers = {
    "Authorization": "Bearer <your_token>"
}

payload = {
  "object_ids": [
    "string"
  ],
  "folder_ids": [
    "string"
  ],
  "update_fields": {
    "parent_id": "string",
    "is_private": true
  }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Create a new object association for usage count and associated objects Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v2/objects/associations
Summary: Create a new object association for usage count and associated objects. Here origin means the assets embedded. Here destination means the document where the assets are being embedded. Here mode can be ADD or REMOVE only.

Description

Create a new object association for usage count and associated objects. Here origin means the assets embedded. Here destination means the document where the assets are being embedded. Here mode can be ADD or REMOVE only.

Request

Payload

Field	Type	Description	Validation
id	string	Unique identifier for the relationship	UUID format
type	string	Type of relationship (e.g., isEmbeddedOf)	Required
origin	object	Origin object details	Required
origin.object_id	string	ID of the origin object	UUID format
origin.version_id	string	Version identifier of the origin object	UUID format
origin.version_no	number	Version number of the origin object	Integer, Required
destination	object	Destination object details	Required
destination.object_id	string	ID of the destination object	UUID format
destination.version_id	string	Version identifier of the destination object	UUID format
source	string	Source reference or metadata	Optional
mode	string	Operation mode (e.g., ADD, REMOVE, UPDATE)	Enum: ADD/REMOVE/UPDATE

{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "isEmbeddedOf",
"origin": {
  "object_id": "",
  "version_id": "",
  "version_no": 1
},
"destination": {
  "object_id": "",
  "version_id": ""
},
"source": "",
"mode": "ADD"
}

Response

{
  "id": "",
  "type": "isEmbeddedOf",
  "sequence_number": 1,
  "origin_object_id": "string",
  "origin_version_id": "string",
  "origin_version_no": 1,
  "origin_title": "",
  "origin_object_type": "",
  "origin_file_name": "",
  "origin_asset_location": "",
  "origin_file_extension": "",
  "associated_at": "2025-12-22T07:01:04.343Z",
  "associated_by": "",
  "destination_object_id": "string",
  "destination_version_id": "string"
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/objects/associations"
headers = {
    "Authorization": "Bearer <your_token>"
}

payload = {
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "isEmbeddedOf",
  "origin": {
    "object_id": "",
    "version_id": "",
    "version_no": 1
  },
  "destination": {
    "object_id": "",
    "version_id": ""
  },
  "source": "",
  "mode": "ADD"
}

response = requests.put(url, headers=headers, json=payload)
print(response.json())

Deassociate the objects in Bulk Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v2/objects/deassociations/bulk
Summary: Deassociate the objects in Bulk

Description

Deassociate the objects in Bulk

Request

Payload

Field	Type	Description	Validation
ids	array	List of object identifiers to update	Each item UUID, Optional
mode	string	Operation mode for the request	Enum: REMOVE

{
"ids": [],
"mode": "REMOVE"
}

Response

{
  "status": "string",
  "message": "string",
  "data": [
    {
      "ids": [],
      "mode": "REMOVE"
    }
  ]
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/objects/deassociations/bulk"
headers = {
    "Authorization": "Bearer <your_token>"
}

payload = {
  "ids": [],
  "mode": "REMOVE"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Get All Asset lists embedded for an Object Id for a specific version Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v2/objects/associations/<object_id>/versions/<version_id>
Summary: Get All Asset lists embedded for an Object Id for a specific version.

Description

Get All Asset lists embedded for an Object Id for a specific version.

Request

Payload

Field	Type	Description	Validation
object_id	string	UUID for the object	UUID format
version_id	string	UUID for the object	UUID format

Response

{
  "status": "string",
  "message": "string",
  "data": [
    {
      "id": "",
      "type": "isEmbeddedOf",
      "sequence_number": 1,
      "origin_object_id": "string",
      "origin_version_id": "string",
      "origin_version_no": 1,
      "origin_title": "",
      "origin_object_type": "",
      "origin_file_name": "",
      "origin_asset_location": "",
      "origin_file_extension": "",
      "associated_at": "2025-12-22T07:05:38.960Z",
      "associated_by": "",
      "destination_object_id": "string",
      "destination_version_id": "string"
    }
  ]
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/objects/associations/<object_id>/versions/<version_id>"
headers = {
    "Authorization": "Bearer <your_token>"
}

response = requests.get(url, headers=headers, json=payload)
print(response.json())

Update the file for object in the object repository Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v2/objects/upload-file-from-generated-asset
Summary: Update the file for object in the object repository.

Description

Update the file for object in the object repository

Request

Payload

Field	Type	Description	Validation
title	string	Title of the asset or chat	Required
asset_id	string	Unique identifier for the asset	UUID format
chat_id	string	Unique identifier for the chat	UUID format
is_agent_chat	boolean	Flag indicating if the chat is agent-based	Required (true/false)
parent_folder_id	string	Identifier of the parent folder	UUID format, Optional
is_private	boolean	Privacy flag for the asset/chat	Required (true/false)

{
"title": "string",
"asset_id": "string",
"chat_id": "string",
"is_agent_chat": true,
"parent_folder_id": "string",
"is_private": false
}

Response

{
  "status": "string",
  "message": "string",
  "data": {
    "status": "string",
    "object_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "version_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "version_no": 1,
    "version_label": "string",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "object_type": "string",
    "title": "string",
    "description": "string",
    "file_name": "string",
    "file_extension": "string",
    "size": 0,
    "mimetype": "string",
    "uri": "string",
    "asset_location": "string",
    "default_asset_thumbnail": "string",
    "created_at": "2025-12-22T09:09:21.962Z",
    "updated_at": "2025-12-22T09:09:21.962Z",
    "deleted_at": "2025-12-22T09:09:21.962Z",
    "created_by_name": "string",
    "created_by_user_id": "string",
    "created_by_user_type": "string",
    "updated_by_name": "string",
    "deleted_by_name": "string",
    "is_latest_version": false,
    "is_deleted": false,
    "is_private": false,
    "is_lga": "string",
    "source": "string",
    "tags": [
      "string"
    ],
    "kvp": {},
    "taxonomy": [
      {
        "uuid": "string",
        "title": "string"
      }
    ],
    "folders": [
      "string"
    ],
    "repos": [
      "string"
    ],
    "metadata": {},
    "media": {},
    "usage_count": 0,
    "license_expiration_date": "2025-12-22T09:09:21.962Z",
    "license_validity": true
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/objects/upload-file-from-generated-asset"
headers = {
    "Authorization": "Bearer <your_token>"
}

payload = {
  "title": "string",
  "asset_id": "string",
  "chat_id": "string",
  "is_agent_chat": true,
  "parent_folder_id": "string",
  "is_private": false
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Chunks V2 APIs

Chunk Search Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v2/chunks/search
Summary: Search for chunks based on similarity search.

Description

Performs a semantic similarity search across chunks.

Request

Payload

{
  "query": "search text",
  "filters": {
    "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "chunk_type": "text",
    "metadata": {
      "key": "value"
    }
  },
  "top_k": 10
}

Response

{
  "status_code": "200",
  "message": "Chunks found",
  "data": {
    "chunks": [{
      "chunk_id": "chunk123",
      "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
      "content": "chunk content",
      "metadata": {
        "key": "value"
      },
      "chunk_type": "text",
      "similarity_score": 0.95
    }]
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/chunks/search"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "query": "search text",
    "filters": {
        "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
        "chunk_type": "text"
    },
    "top_k": 10
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Chunk Creation Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v2/chunks
Summary: Creates a new chunk in the repository.

Description

Creates a new chunk with content and metadata.

Request

Payload

Field	Type	Description	Validation
object_id	string	UUID of the associated object	Required, UUID format
content	string	Chunk content	Required
metadata	object	Metadata for the chunk	Optional
metadata.key	string	Metadata key	Optional
metadata.value	string	Metadata value	Optional
chunk_type	string	Type of the chunk	Required, Enum: text, file
embedding	object	Embedding information	Required for vector chunks
embedding.vector	array	Vector array (float)	Required for vector chunks
embedding.model	string	Model used for embedding	Required for vector chunks

{
  "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
  "content": "chunk content",
  "metadata": {
    "key": "value"
  },
  "chunk_type": "text",
  "embedding": {
    "vector": [0.1, 0.2, 0.3],
    "model": "gte-small"
  }
}

Response

{
  "status_code": "201",
  "message": "Chunk created",
  "data": {
    "chunk_id": "chunk123"
  }
}

Usage

import requests
import numpy as np

url = "https://api.kadal.ai/cl/api/v2/chunks"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "content": "chunk content",
    "metadata": {"key": "value"},
    "chunk_type": "text",
    "embedding": {
        "vector": np.random.rand(384).tolist(),  # Example vector
        "model": "gte-small"
    }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Chunk Update Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v2/chunks/{chunk_id}
Summary: Updates an existing chunk.

Description

Updates content or metadata of an existing chunk.

Request

Query Parameters
- chunk_id (path): ID of the chunk to update

Payload

{
  "content": "updated content",
  "metadata": {
    "key": "new_value"
  }
}

Response

{
  "status_code": "200",
  "message": "Chunk updated"
}

Usage

import requests

chunk_id = "chunk123"
url = f"https://api.kadal.ai/cl/api/v2/chunks/{chunk_id}"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "content": "updated content",
    "metadata": {"key": "new_value"}
}

response = requests.put(url, headers=headers, json=payload)
print(response.json())

Chunk Deletion Endpoint

Method: DELETE
Path: https://api.kadal.ai/cl/api/v2/chunks/{chunk_id}
Summary: Deletes a chunk.

Description

Removes a chunk from the repository.

Request

Query Parameters
- chunk_id (path): ID of the chunk to delete

Response

{
  "status_code": "200",
  "message": "Chunk deleted"
}

Usage

import requests

chunk_id = "chunk123"
url = f"https://api.kadal.ai/cl/api/v2/chunks/{chunk_id}"
headers = {
    "Authorization": "Bearer <your_token>"
}

response = requests.delete(url, headers=headers)
print(response.json())

Bulk Chunks Creation Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v2/chunks/bulk
Summary: Creates multiple chunks in a single request.

Description

Bulk creation of chunks.

Request

Payload

{
  "chunks": [{
    "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "content": "chunk content 1",
    "metadata": {
      "key": "value1"
    }
  },
  {
    "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "content": "chunk content 2",
    "metadata": {
      "key": "value2"
    }
  }]
}

Response

{
  "status_code": "201",
  "message": "Chunks created",
  "data": {
    "chunk_ids": ["chunk123", "chunk124"]
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/chunks/bulk"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "chunks": [{
        "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
        "content": "chunk content 1",
        "metadata": {"key": "value1"}
    },
    {
        "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
        "content": "chunk content 2",
        "metadata": {"key": "value2"}
    }]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Bulk Chunks Deletion Endpoint

Method: DELETE
Path: https://api.kadal.ai/cl/api/v2/chunks/object/bulk
Summary: Deletes all chunks for an object.

Description

Removes all chunks associated with specified objects.

Request

Payload

{
  "object_ids": [
    "1ea3d628-f555-41c7-8101-c56a65087bab",
    "2fb4d839-g666-52d8-9212-d67b76198bac"
  ]
}

Response

{
  "status_code": "200",
  "message": "Object chunks deleted"
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/chunks/object/bulk"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "object_ids": [
        "1ea3d628-f555-41c7-8101-c56a65087bab",
        "2fb4d839-g666-52d8-9212-d67b76198bac"
    ]
}

response = requests.delete(url, headers=headers, json=payload)
print(response.json())

File Upload V3 APIs

Upload Files

Method: POST
Path: https://api.kadal.ai/cl/api/v3/file_upload
Summary: Upload files to the chat interface.

Description

Uploads files to the chat interface with support for various file types.

Request

Query Parameters
- files (form-data, required): List of files to upload
- folder_id (query, required): The my folder ID where files should be uploaded
- source_category (query, required): Category of the source (KnowledgeBase/Guideline/OutputTemplate/InputFile)
- session_id (query, required): Chat interface session ID

Response

{
  "status_code": "200",
  "message": "Files uploaded successfully",
  "data": {
    "files": [{
      "file_name": "document.pdf",
      "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
      "status": "uploaded"
    }]
  }
}

Other Responses
- 413 Payload Too Large: File size exceeds limit
- 415 Unsupported Media Type: Invalid file type

Usage

import requests

url = "https://api.kadal.ai/cl/api/v3/file_upload"
headers = {
    "Authorization": "Bearer <your_token>"
}
params = {
    "folder_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "source_category": "KnowledgeBase",
    "session_id": "5678"
}
files = {
    'files': [
        ('document.pdf', open('document.pdf', 'rb'), 'application/pdf'),
        ('image.jpg', open('image.jpg', 'rb'), 'image/jpeg')
    ]
}

response = requests.post(url, headers=headers, params=params, files=files)
print(response.json())

Project APIs

Create Project Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v1/project
Summary: Create a new project in the folders collection with schema_version 2.0.

Description

Creates a new project under a specified parent folder. Projects are distinct from regular folders and support team membership, agent associations, and project-level settings.

Request

Content-Type: application/json
Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	string	UUID	No

Payload

Parameter	Description	Data Type	Allowed Values	Required
name	Project display name (1–255 characters)	String		Yes
parent_id	Parent folder UUID; cannot point to another Project	String (UUID)		Yes
description	Project description (min 1 character)	String		Yes
icon	Valid icon reference or URL	String		No
custom_metadata	Extended metadata	Object	`{ kvp: [], tags: [], taxonomy: [] }`	No
settings	Project-level settings	Object	`{ search_scope: string, version: string }`	No

Response

{
  "status": "success",
  "data": {
    "schema_version": "2.0",
    "tenant_id": "<tenant-uuid>",
    "folder_id": "<project-uuid>",
    "name": "My Project",
    "description": "A new project for organizing content",
    "icon": "icon_project_default",
    "type": "Project",
    "parent_id": "<parent-folder-uuid>",
    "is_private": false,
    "children": [],
    "custom_metadata": {
      "kvp": [
        { "color": "red" }
      ],
      "tags": [
        { "name": "tag1", "is_system": false }
      ],
      "taxonomy": []
    },
    "team": [
      {
        "user_id": "<user-uuid>",
        "user_name": "user@example.com",
        "user_email": "user@example.com",
        "role": "Creator",
        "role_id": null,
        "added_on": "2026-06-04T09:33:15.798293Z",
        "added_by": "<user-uuid>",
        "added_by_name": "user@example.com"
      }
    ],
    "agents": [],
    "settings": {
      "search_scope": "current_project",
      "version": "1.0"
    },
    "created_by": "<user-uuid>",
    "created_by_name": "user@example.com",
    "created_on": "2026-06-04T09:33:15.798293Z",
    "updated_by": null,
    "updated_by_name": null,
    "updated_on": "2026-06-04T09:33:15.798293Z",
    "duplicate_status": null,
    "is_deleted": false,
    "deleted_by": null,
    "deleted_on": null
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v1/project"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "name": "My Project",
    "parent_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "description": "A new project for organizing content",
    "icon": "https://example.com/icon.svg",
    "custom_metadata": {
        "kvp": [],
        "tags": [],
        "taxonomy": []
    },
    "settings": {
        "search_scope": "project",
        "version": "1.0"
    }
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Update Project Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v1/project/{id}
Summary: Update an existing project.

Description

Updates an existing project's metadata. Enforced rules:

type and team are immutable via this endpoint.
is_private cannot be changed to true.
parent_id cannot point to another Project.
Requesting user must be Creator, Editor, or Tenant Admin.
description is mandatory if included in the request.

Request

Content-Type: application/json
Path Parameters

Parameter	Description	Data Type	Required
id	Project UUID to update	String (UUID)	Yes

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	string	UUID	No

Payload

Parameter	Description	Data Type	Allowed Values	Required
name	Project display name (1–255 characters)	String		No
description	Project description (min 1 character)	String		No
icon	Valid icon reference or URL	String		No
custom_metadata	Extended metadata	Object	`{ kvp: [], tags: [] }`	No
settings	Project-level settings	Object	`{ search_scope: string }`	No

Response

{
  "status": "success",
  "data": {
    "folder_id": "<project-uuid>",
    "name": "Updated Project Name",
    "description": "Updated project description",
    "icon": "",
    "updated_on": "2026-06-04T09:34:18.117231Z",
    "updated_by": "<user-uuid>"
  }
}

Usage

import requests

project_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/project/{project_id}"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "name": "Updated Project Name",
    "description": "Updated project description",
    "icon": "https://example.com/new-icon.svg",
    "custom_metadata": {
        "kvp": [],
        "tags": ["updated"]
    },
    "settings": {
        "search_scope": "tenant"
    }
}

response = requests.put(url, headers=headers, json=data)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Get Project Endpoint

Method: GET
Path: https://api.kadal.ai/cl/api/v1/project/{id}
Summary: Get a project by ID.

Description

Retrieves a project by its UUID. Access rules:

Team members and Tenant Admins receive full project details.
Non-members receive a restricted response (name, id, type only).

Request

Path Parameters

Parameter	Description	Data Type	Required
id	Project UUID	String (UUID)	Yes

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
include_children	Fetch first-level child folders	Boolean	Default: `false`	No
include_team	Include team members array	Boolean	Default: `true`	No
include_agents	Include agents array	Boolean	Default: `true`	No
ext_user_id_ref	External user ID reference	String	UUID	No

Response

{
  "status": "success",
  "data": {
    "folder_id": "<project-uuid>",
    "tenant_id": "<tenant-uuid>",
    "name": "My Project",
    "description": "Project description",
    "icon": "",
    "type": "Project",
    "parent_id": "<parent-folder-uuid>",
    "is_private": false,
    "created_by": "<user-uuid>",
    "created_by_name": "user@example.com",
    "created_on": "2026-04-14T11:07:00.458899Z",
    "updated_by": "<user-uuid>",
    "updated_by_name": "user@example.com",
    "updated_on": "2026-04-27T11:46:36.996792Z",
    "custom_metadata": {
      "kvp": [],
      "tags": [],
      "taxonomy": []
    },
    "settings": {
      "search_scope": "current_project",
      "version": "1.0"
    },
    "schema_version": "2.0",
    "duplicate_status": null,
    "access_level": "Editor",
    "is_starred": false,
    "team": [
      {
        "user_id": "<user-uuid>",
        "user_name": "user@example.com",
        "user_email": "user@example.com",
        "role": "Creator",
        "role_id": null,
        "added_on": "2026-04-14T11:07:00.458899Z",
        "added_by": "<user-uuid>",
        "added_by_name": "user@example.com",
        "firstName": "Jane",
        "lastName": "Doe",
        "is_tenant_user_active": "active"
      },
      {
        "user_id": "<member-uuid>",
        "user_name": "Member User",
        "user_email": "member@example.com",
        "role": "Editor",
        "role_id": "<role-uuid>",
        "added_on": "2026-04-14T11:07:57.680761Z",
        "added_by": "<user-uuid>",
        "added_by_name": "user@example.com",
        "firstName": "Member",
        "lastName": "User",
        "is_tenant_user_active": "active"
      }
    ],
    "children": [
      {
        "tenant_id": "<tenant-uuid>",
        "name": "folder 1",
        "is_private": false,
        "type": "Folder",
        "is_project": true,
        "project_id": "<project-uuid>",
        "description": "",
        "parent_id": "<project-uuid>",
        "folder_id": "<folder-uuid>",
        "created_by": "<user-uuid>",
        "created_by_name": "user@example.com",
        "created_on": "2026-04-28 10:54:31.354050",
        "updated_on": "2026-04-28 10:54:31.354058",
        "updated_by": null,
        "updated_by_name": null,
        "custom_metadata": {
          "tags": [],
          "kvp": [],
          "taxonomy": []
        },
        "children": [],
        "is_deleted": false,
        "deleted_by": null,
        "deleted_on": null
      }
    ]
  }
}

Usage

import requests

project_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/project/{project_id}"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

params = {
    "include_children": False,
    "include_team": True,
    "include_agents": True
}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Delete Project Endpoint

Method: DELETE
Path: https://api.kadal.ai/cl/api/v1/project/{id}
Summary: Delete a project.

Description

Deletes a project. Enforced rules:

Only Creator or Tenant Admin can delete.
confirm parameter must be true.
If cascade=false and children exist, returns error 400.
Cascade deletes all child folders, objects, and team access.

Request

Path Parameters

Parameter	Description	Data Type	Required
id	Project UUID to delete	String (UUID)	Yes

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
confirm	Must be `true` to confirm deletion	Boolean	`true`	Yes
cascade	Delete all children if `true`	Boolean	Default: `false`	No
ext_user_id_ref	External user ID reference	String	UUID	No

Response

{
  "status": "success",
  "data": {
    "folder_id": "<project-uuid>",
    "deleted_on": "2026-04-16T12:56:08.322597Z",
    "message": "Project deleted successfully"
  }
}

Usage

import requests

project_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/project/{project_id}"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

params = {
    "confirm": True,
    "cascade": True
}

response = requests.delete(url, headers=headers, params=params)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

List Projects Endpoint

Method: GET
Path: https://api.kadal.ai/cl/api/v1/projects
Summary: List all projects for the authenticated tenant with pagination, filtering, and sorting.

Description

Returns all projects for the authenticated tenant. Access levels:

member — only projects the user belongs to.
restricted — only non-member projects.
all — everything.

Each project entry carries an access_level field reflecting the requesting user's role or restricted.

Request

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
page	Page number (1-based)	Integer ≥ 1	Default: `1`	No
page_size	Results per page (max 100)	Integer 1–100	Default: `20`	No
parent_id	Filter by parent folder UUID	String	UUID	No
access_level	Filter by access level	String	`member`, `restricted`, `all`; Default: `"all"`	No
sort_by	Sort field	String	`created_on`, `updated_on`, `name`; Default: `"updated_on"`	No
sort_order	Sort direction	String	`asc`, `desc`; Default: `"desc"`	No
ext_user_id_ref	External user ID reference	String	UUID	No

Response

{
  "status": "success",
  "data": {
    "projects": [
      {
        "folder_id": "<project-uuid>",
        "name": "My Project",
        "description": "Project description",
        "icon": "",
        "created_on": "2026-05-29T05:13:14.763266Z",
        "updated_on": "2026-05-29T05:13:14.763266Z",
        "parent_id": "<parent-folder-uuid>",
        "custom_metadata": {
          "kvp": [],
          "tags": [],
          "taxonomy": []
        },
        "settings": {
          "search_scope": "current_project",
          "version": "1.0"
        },
        "access_level": "Tenant Admin",
        "is_starred": false
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_count": 98,
      "total_pages": 5
    }
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v1/projects"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

params = {
    "page": 1,
    "page_size": 20,
    "access_level": "all",
    "sort_by": "updated_on",
    "sort_order": "desc"
}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Add Team Member Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v1/project/{id}/team
Summary: Add a team member to the project.

Description

Adds one or more team members to the project. Enforced rules:

Only Creator, Editor, or Tenant Admin can add members.
User cannot already be in the team.
Role must be valid (Editor, Viewer, Commenter).
Cannot add user with Creator role.

Request

Content-Type: application/json
Path Parameters

Parameter	Description	Data Type	Required
id	Project UUID	String (UUID)	Yes

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	String	UUID	No

Payload

Array of team member objects:

Parameter	Description	Data Type	Allowed Values	Required
user_id	UUID of the team member	String (UUID)		Yes
user_name	Display name (ignored — resolved from DB)	String	Default: `""`	No
user_email	Email (ignored — resolved from DB)	String	Default: `""`	No
role	Role of the team member	String	Admin, Editor, Viewer, Commenter, No Access, Repository Manager	Yes
role_id	UUID of the global role	String (UUID)		Yes

Response

{
  "status": "success",
  "data": {
    "added": [
      {
        "user_id": "<user-uuid>",
        "user_name": "Member User",
        "user_email": "member@example.com",
        "role": "Viewer",
        "role_id": "<role-uuid>",
        "added_on": "2026-06-04T09:40:06.178363Z",
        "added_by": "<requesting-user-uuid>",
        "added_by_name": "user@example.com"
      }
    ]
  }
}

Usage

import requests

project_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/project/{project_id}/team"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = [
    {
        "user_id": "user-uuid-here",
        "user_name": "John.Smith",
        "user_email": "John.Smith@mail.com",
        "role": "Editor",
        "role_id": "role-uuid-here"
    }
]

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Update Team Member Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v1/project/{id}/team
Summary: Bulk update team members: update role or revoke access.

Description

Bulk updates team members' roles or revokes their access. Enforced rules:

Cannot change Creator's role.
Only Creator or Tenant Admin can update roles.
New role must be valid (Editor, Viewer, Commenter).
Set revoke_access=true to remove a member instead of updating their role.

Request

Content-Type: application/json
Path Parameters

Parameter	Description	Data Type	Required
id	Project UUID	String (UUID)	Yes

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	String	UUID	No

Payload

Array of update objects:

Parameter	Description	Data Type	Allowed Values	Required
user_id	UUID of the team member to update or revoke	String (UUID)		Yes
role	New role; required when `revoke_access` is `false`	String	Admin, Editor, Viewer, Commenter, No Access, Repository Manager	No
role_id	UUID of the global role being assigned; required when `revoke_access` is `false`	String (UUID)		No
revoke_access	If `true`, remove user from team instead of updating role	Boolean	Default: `false`	No

Response

{
  "status": "success",
  "data": {
    "updated": [
      {
        "user_id": "<user-uuid>",
        "role": "Admin"
      }
    ],
    "revoked": [],
    "updated_on": "2026-06-04T09:37:43.731324Z",
    "updated_by": "<requesting-user-uuid>"
  }
}

Usage

import requests

project_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/project/{project_id}/team"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = [
    {
        "user_id": "user-uuid-1",
        "role": "Viewer",
        "role_id": "role-uuid-here",
        "revoke_access": False
    },
    {
        "user_id": "user-uuid-2",
        "revoke_access": True
    }
]

response = requests.put(url, headers=headers, json=data)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Remove Team Members Endpoint

Method: DELETE
Path: https://api.kadal.ai/cl/api/v1/project/{id}/team
Summary: Remove team member(s) from the project.

Description

Removes one or more team members from the project. Enforced rules:

Cannot remove Creator.
Only Creator or Tenant Admin can remove members.
Content created by removed user remains in the project.

Request

Content-Type: application/json
Path Parameters

Parameter	Description	Data Type	Required
id	Project UUID	String (UUID)	Yes

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	String	UUID	No

Payload

Parameter	Description	Data Type	Allowed Values	Required
user_id	List of user UUIDs to remove	Array of Strings (non-empty)		Yes

Response

{
  "status": "success",
  "message": "Team member(s) removed successfully"
}

Usage

import requests

project_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/project/{project_id}/team"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "user_id": ["user-uuid-1", "user-uuid-2"]
}

response = requests.delete(url, headers=headers, json=data)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Add Agent Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v1/project/{id}/agents
Summary: Add one or more agents to the project.

Description

Adds agents to the project. Enforced rules:

Only Creator, Editor, or Tenant Admin can add agents.
No agent in the list can already be in the project agents array.
Duplicate agent_ids within the request are not allowed.
Total agent count cannot exceed 100.

Request

Content-Type: application/json
Path Parameters

Parameter	Description	Data Type	Required
id	Project UUID	String (UUID)	Yes

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	String	UUID	No

Payload

Array of agent objects:

Parameter	Description	Data Type	Allowed Values	Required
agent_id	UUID of the agent	String (UUID)		Yes
is_local	Whether the agent is local to the project	Boolean	Default: `true`	No
is_active	Whether the agent is active	Boolean	Default: `true`	No

Response

{
  "status": "success",
  "data": {
    "agents": [
      {
        "agent_id": "<agent-uuid>",
        "is_local": false,
        "is_active": true,
        "created_on": "2026-06-04T09:38:56.322771Z",
        "created_by": "<user-uuid>",
        "created_by_name": "user@example.com"
      }
    ]
  }
}

Usage

import requests

project_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/project/{project_id}/agents"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = [
    {
        "agent_id": "agent-uuid-here",
        "is_local": True,
        "is_active": True
    }
]

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Remove Agents Endpoint

Method: DELETE
Path: https://api.kadal.ai/cl/api/v1/project/{id}/agents
Summary: Remove agent(s) from the project.

Description

Removes one or more agents from the project. Enforced rules:

Only Creator, Editor, or Tenant Admin can remove agents.
Agent must exist in the project.

Request

Content-Type: application/json
Path Parameters

Parameter	Description	Data Type	Required
id	Project UUID	String (UUID)	Yes

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	String	UUID	No

Payload

Parameter	Description	Data Type	Allowed Values	Required
agent_id	List of agent UUIDs to remove	Array of Strings (non-empty)		Yes

Response

{
  "status": "success",
  "message": "Agent removed from project",
  "data": {
    "agent_id": [
      "<agent-uuid-1>",
      "<agent-uuid-2>"
    ],
    "removed_on": "2026-02-25T07:54:52.758521Z"
  }
}

Usage

import requests

project_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/project/{project_id}/agents"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "agent_id": ["agent-uuid-1", "agent-uuid-2"]
}

response = requests.delete(url, headers=headers, json=data)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Update Agent Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v1/project/{id}/agents/{agent_id}
Summary: Update an agent's status in the project.

Description

Updates an agent's active status within the project. Enforced rules:

Only Creator, Editor, or Tenant Admin can update agents.
Agent must exist in the project.

Request

Content-Type: application/json
Path Parameters

Parameter	Description	Data Type	Required
id	Project UUID	String (UUID)	Yes
agent_id	Agent UUID	String (UUID)	Yes

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	String	UUID	No

Payload

Parameter	Description	Data Type	Allowed Values	Required
is_active	Whether the agent should be active	Boolean	`true`, `false`	Yes

Response

{
  "status": "success",
  "data": {
    "agent_id": "<agent-uuid>",
    "is_active": true,
    "updated_on": "2026-02-25T07:52:42.134367Z"
  }
}

Usage

import requests

project_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
agent_id = "agent-uuid-here"
url = f"https://api.kadal.ai/cl/api/v1/project/{project_id}/agents/{agent_id}"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "is_active": True
}

response = requests.put(url, headers=headers, json=data)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Move Content Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v1/project/move
Summary: Move folders and/or objects into a different destination folder.

Description

Moves one or more folders or objects to a specified destination folder. Permissions are re-evaluated at the destination. If permissions are removed for any content, the permissions_removed array will list the affected items.

Request

Content-Type: application/json
Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	String	UUID	No

Payload

Parameter	Description	Data Type	Allowed Values	Required
object_ids	List of object UUIDs to move	Array of Strings	UUIDs	No
folder_ids	List of folder UUIDs to move	Array of Strings	UUIDs	No
destination_folder_id	Target folder UUID to move content into	String (UUID)		Yes

Response

{
  "status": "success",
  "data": {
    "moved_count": 1,
    "destination_folder_id": "<destination-folder-uuid>",
    "permissions_removed": [],
    "message": "Content moved successfully"
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v1/project/move"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "object_ids": ["object-uuid-1"],
    "folder_ids": ["folder-uuid-1"],
    "destination_folder_id": "destination-folder-uuid"
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Directory APIs​

Root Directory Retrieval Endpoint​

Description​

Request​

Query Parameters​

Response​

Usage​

Root Directory Creation Endpoint​

Description​

Request​

Query Parameters​

Payload​

Response​

Other Responses​

Usage​

Directory Retrieval Endpoint​

Description​

Request​

Query Parameters​

Response​

Directory Metadata Update Endpoint​

Description​

Request​

Path Parameters​

Query Parameters​

Payload​

Response​

Other Responses​

Usage​

Child Directories Addition Endpoint​

Description​

Request​

Path Parameters​

Query Parameters​

Payload​

Response​

Other Responses​

Usage​

Directory Deletion Endpoint​

Description​

Request​

Query Parameters​

Response​

Usage​

Bulk Directory Retrieval Endpoint​

Description​

Request​

Query Parameters​

Payload​

Response​

Directory Search Endpoint​

Description​

Request​

Query Parameters​

Response​

My Folder APIs​

My Folder Upsert Endpoint​

Description​

Response​

Other Responses​

Notes​

Usage​

Get Objects Content API​

Description​

Request​

Path Parameters​

Query Parameters​

Response​

Other Responses​

Usage​

Objects V2 APIs​

Object Creation Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Object Update Endpoint​

Description​

Request​

Directory APIs

Root Directory Retrieval Endpoint

Description

Request

Query Parameters

Response

Usage

Root Directory Creation Endpoint

Description

Request

Query Parameters

Payload

Response

Other Responses

Usage

Directory Retrieval Endpoint

Description

Request

Query Parameters

Response

Directory Metadata Update Endpoint

Description

Request

Path Parameters

Query Parameters

Payload

Response

Other Responses

Usage

Child Directories Addition Endpoint

Description

Request

Path Parameters

Query Parameters

Payload

Response

Other Responses

Usage

Directory Deletion Endpoint

Description

Request

Query Parameters

Response

Usage

Bulk Directory Retrieval Endpoint

Description

Request

Query Parameters

Payload

Response

Directory Search Endpoint

Description

Request

Query Parameters

Response

My Folder APIs

My Folder Upsert Endpoint

Description

Response

Other Responses

Notes

Usage

Get Objects Content API

Description

Request

Path Parameters

Query Parameters

Response

Other Responses

Usage

Objects V2 APIs

Object Creation Endpoint

Description

Request

Payload

Response

Usage

Object Update Endpoint

Description

Request